Problem

Hosted Codex Apps already speak MCP, but Codex does not currently treat them like ordinary MCP servers.

Today they enter the client as one reserved codex_apps server. Generic MCP and core code then unpack connector annotations from that server's tool list and reconstruct product concepts that MCP should not need to understand:

• codex-mcp and the connection manager recognize the reserved server, parse connector identity, create connector-specific namespaces, and carry Apps-specific cache, reconnect, auth, approval, file, and refresh behavior.
• core imports connector types, derives app inventory from MCP tools, renders Apps instructions, handles Apps-specific approval and file paths, tracks connector analytics/presentation, and hard-refreshes Apps after installs.
• app-server has to construct or query generic MCP machinery when it only wants product-level Apps inventory or auth state.

That inversion makes every Apps behavior a cross-cutting change. It also creates two lifecycle paths for what is fundamentally the same thing: an MCP server with tools, resources, authentication, approvals, and a connection lifecycle.

The target invariant is:

core, codex-mcp, the MCP connection manager, and mcp-server see only ordinary MCP server registrations. They contain no direct Apps/connector dependencies, reserved-name checks, or product-specific branches.

One compatibility seam remains in protocol serialization: generic McpToolSource accessors still serialize the historical connector_id/connector_name/connector_description fields consumed by Guardian and rollout clients. The prototype does not branch on those fields in generic layers, but the boundary verifier cannot prove that semantic distinction.

Product-aware hosts may still use the shared Apps service directly. In particular, app-server should list Apps and read auth/install state from the Apps owner rather than reverse-engineering them from generic MCP tool state. Runtime Apps authentication remains an Apps-owned elicitation flow.

Review priorities, in order

These priorities are ordered. A lower item should not compromise a higher one.

1. Enforce the ownership boundary. No direct Apps/connector dependencies, reserved-name checks, or product-specific branches in protected generic layers.
2. Preserve trust and authorization boundaries. Runtime credentials, auth revision, approval identity, private metadata, file permissions, and resource access cannot become weaker to simplify the move.
3. Preserve user-visible behavior at its natural owner. Namespaces, policy, approvals, elicitations, files, resources, app listing, plugin attribution, analytics, and presentation should continue unless this PR names the change explicitly.
4. Keep one canonical path from the generic MCP boundary inward. After the Apps adapter exposes loopback servers, they use the same catalog, HTTP client, reconciliation, tool-call, resource, and shutdown machinery as any other MCP server.
5. Make publication consistent and startup non-blocking. A turn sees one immutable Apps generation; cache/retry/discovery cannot block the model boundary or expose a mixed inventory.
6. Add only reusable generic mechanisms. A runtime-owned MCP server needs credentials, lifetime ownership, trusted metadata, deterministic precedence, and revisioned contribution. None of those abstractions should mention Apps.
7. Land in independently green slices. The prototype can be large; the landing sequence should not leave duplicate production paths or an unwired crate between stages.

Intentional or stricter behavior changes

These are not described as code motion. They need explicit reviewer agreement before landing.

1. Cold discovery no longer blocks the first model request. With no cached/published generation, the first cold turn can proceed without Apps tools or Apps instructions. Background discovery publishes a generation for a later safe boundary. This removes startup latency and failure coupling, but it is a visible availability tradeoff.

2. The current prototype exposes the real MCP topology through app-server. mcpServerStatus/list changes from one codex_apps entry with grouped tools to a resource-only codex_apps entry plus one codex_apps__<connector> entry per materialized connector namespace. This is not required by the core/MCP ownership boundary because app-server is allowed to understand Apps; preserving the aggregate public shape is an open landing decision. Connector resource reads already remain restricted to declared URIs.

3. Generic OAuth does not claim runtime Apps servers. mcpServer/oauth/login rejects these runtime-only registrations. Apps auth remains the private auth-elicitation/install flow owned by the Apps adapter and extension.

4. The current prototype makes generic install suggestion tools plugin-only. Standalone connectors are no longer returned by list_available_plugins_to_install or accepted by request_plugin_install. This also means codex-tui has no model-driven install candidate when only standalone connectors are available. The architecture does not require that regression: if standalone model-driven installation remains required, it should move behind an Apps-owned extension surface rather than disappear or return as a core branch.

5. Plugin and Apps guidance follows callable MCP namespaces. Model-facing plugin instructions no longer render a separate “Apps from this plugin” list; declared Apps appear through their contributed MCP namespaces and attribution. Apps instructions retain include_apps_instructions but now require at least one policy-enabled tool in the published snapshot, avoiding instructions for an App with nothing callable.

6. Explicit/implicit Apps analytics become turn-local. The previous session-global connector selection made every later use look explicit. The extension now classifies explicit use from raw mentions in the current turn. This fixes sticky classification, but an app mention introduced by a skill no longer counts as an explicit user mention.

7. Malformed inventory is handled more strictly. Blank tool names and incomplete connector identity are omitted; inconsistent display names for one stable connector ID reject the generation. Synthetic-only connectors remain available for auth/install checks but do not become installed Apps or callable connector servers.

8. Legacy provenance-free Apps caches are not migrated. Old entries cannot prove their upstream URL or SKU. Ignoring them avoids cross-origin/account reuse, but the first run after upgrade may require live discovery.

9. File handling is stricter. The old path could read from the primary environment without exact sandbox context. The new path requires the pinned environment generation, rejects stale instances and malformed arrays, and checks actual buffered size. Cancellation prevents partial argument rewriting or an upstream invocation, but does not roll back uploads that already completed.

10. Collision precedence is explicit. An enabled configured server loses to a generated Apps registration with the same connector name. An explicitly disabled same-name server remains a veto for that registration; a disabled configured codex_apps singleton vetoes the whole Apps bundle for compatibility.

11. Literal-loopback proxy/redirect hardening is generic. The no-proxy rule and literal-loopback redirect restriction live in the shared exec-server HTTP path, so their safety benefit and compatibility impact extend beyond Apps.

Known blockers and open decisions

These are prototype findings, not claims that the branch is landing-ready.

Architecture at a glance

Names and endpoints

Before and after

flowchart LR
  subgraph BEFORE["Before: one remote endpoint, one reserved local name"]
    direction TB
    B_CLIENT["Codex MCP client"]
    B_NAME["local registration: codex_apps"]
    B_REMOTE["actual remote HTTP MCP: /backend-api/ps/mcp"]
    B_TOOLS["one logical, potentially paginated tool inventory"]
    B_SPECIAL["codex-mcp + core decode connector metadata and synthesize namespaces"]
    B_CLIENT --> B_NAME --> B_REMOTE --> B_TOOLS --> B_SPECIAL
  end

  subgraph AFTER["After: the product adapter publishes ordinary MCP registrations"]
    direction TB
    A_REMOTE["same Hosted Apps upstream: /backend-api/ps/mcp"]
    A_OWNER["codex-apps + Apps extension: product-aware owner"]
    A_HTTP["one loopback listener per immutable generation"]
    A_ROUTES["HTTP routes: codex_apps resources; codex_apps__calendar tools; codex_apps__gmail tools"]
    A_GENERIC["generic catalog → connection manager → core"]
    A_REMOTE <-->|"inventory + forwarding"| A_OWNER
    A_OWNER --> A_HTTP --> A_ROUTES --> A_GENERIC
    A_OWNER -. "direct inventory + auth state" .-> A_APP["app-server"]
  end

There is one 127.0.0.1:0 listener per immutable generation, not one listener or process per connector. Each route becomes a separate EffectiveMcpServer registration with its own URL path, runtime-only bearer, policy, and trusted metadata.

Ownership boundary

flowchart TB
  subgraph PRODUCT["Product-aware zone"]
    direction LR
    APP["app-server: direct list, auth, and install APIs"]
    EXT["Apps extension: eligibility, lifecycle, policy, presentation, analytics"]
    APPS["codex-apps: inventory, cache, HTTP adapter, files, resources, auth"]
    SUPPORT["plugin + connectors: product inputs"]
    APP -->|"direct service"| EXT -->|"owns"| APPS
    SUPPORT -->|"declarations + policy"| EXT
    SUPPORT -->|"naming helpers"| APPS
  end

  subgraph GENERIC["Product-agnostic zone"]
    direction LR
    API["extension-api: revisioned effective servers"]
    CORE["core: safe-boundary orchestration"]
    MCP["codex-mcp: catalog + client reconciliation"]
    PATH["ordinary MCP tool, resource, and approval path"]
    API --> CORE --> MCP --> PATH
  end

  EXT -->|"server contributions"| API
  MCP -->|"Streamable HTTP calls to loopback routes"| APPS

mcp-server only constructs and shuts down an opaque host-extension bundle, then passes the registry to core. exec-server and rmcp-client provide generic loopback safety and bounded HTTP responses.

Exposed MCP topology

Cost and isolation tradeoff

• The adapter adds one loopback HTTP hop and one listener per live generation.
• Before this PR, Codex normally held one upstream MCP client connection to /ps/mcp. Afterward, inventory uses a shared discovery connection and every used downstream MCP session lazily opens its own upstream session. That increases connection fanout, but prevents an elicitation in one connector/session from blocking another.

Changed-module behavior map

This table covers every production module group in the diff. Test fixtures, manifests, generated build metadata, and Cargo.lock follow the owner they validate or register.

Build manifests register the new crate and dependency direction; the approval template asset moves from core to codex-apps unchanged.

Why these structural choices

Runtime flows

Cold start and discovery

sequenceDiagram
  participant Core as core safe boundary
  participant Catalog as core MCP resolver
  participant Apps as Apps extension
  participant Upstream as Hosted Apps /ps/mcp
  participant Manager as connection manager

  Core->>Catalog: resolve contributions (Discover)
  Catalog->>Apps: current snapshot + revision?
  Apps-->>Catalog: return immediately (possibly empty)
  Note over Core,Apps: Cold contribution does not await network discovery
  Apps->>Upstream: background inventory fetch
  Upstream-->>Apps: complete connector/tool inventory
  Apps->>Apps: validate + build immutable generation
  Apps->>Apps: publish registrations + increment revision
  Core->>Catalog: next safe-boundary resolve
  Catalog->>Apps: read published generation
  Apps-->>Catalog: resource server + connector servers
  Catalog->>Manager: resolved ordinary MCP catalog
  Manager->>Manager: reconcile and reuse compatible client connections
  Note over Apps,Manager: Failed refresh keeps the last-good generation published

Connector tool call

sequenceDiagram
  participant Core as core generic tool path
  participant MCP as codex-mcp client
  participant App as connector loopback MCP
  participant Env as pinned environment
  participant Backend as ChatGPT backend

  Core->>MCP: call server codex_apps__calendar / tool create_event
  Note over Core,MCP: Generic policy and approval use trusted runtime metadata
  MCP->>App: HTTP MCP call + route-specific bearer
  App->>App: verify route, generation, Origin, and auth guard
  opt Schema declares file parameters
    App->>Env: read with pinned instance + sandbox context
    Env-->>App: bytes or fail closed
    App->>Backend: upload through file API
  end
  App->>App: routed name → stable upstream tool identity
  App->>Backend: /ps/mcp tools/call with sanitized metadata
  Backend-->>App: result or elicitation request
  opt Elicitation required
    App->>MCP: bridge to the initiating downstream session
    MCP-->>App: elicitation response
  end
  App-->>MCP: ordinary result + trusted effective input when rewritten
  MCP-->>Core: ordinary MCP result
  Note over App,Backend: Each downstream session lazily owns one upstream MCP session

Refresh, auth change, and in-flight work

flowchart TB
  START["Published generation G1: listener P1, bearer B1, auth revision R1"]
  TRIGGER{"What changed?"}
  AUTH_EVENT["Re-evaluate auth and Apps eligibility"]
  BUILD["Build G2 off to the side: new listener P2 and new bearers"]
  REMOVE["If no longer eligible: publish removal contributions"]
  PUBLISH["Atomic Apps publication: G2 becomes available for contribution"]
  RECONCILE["Next safe boundary: catalog adopts the change and reconciles clients"]
  OLD["Pinned G1 remains alive while snapshot/runtime owners retain it"]
  KIND{"Did auth revision change?"}
  NORMAL["No: pinned G1 sessions remain valid until released"]
  AUTH["Yes: reject new G1 requests and recheck before upstream forward"]
  INFLIGHT["A call already forwarded upstream may finish"]
  DROP["Last G1 owner drops: cancel sessions and stop listener"]

  START --> TRIGGER
  TRIGGER -->|"inventory refresh"| BUILD
  TRIGGER -->|"login, logout, or token change"| AUTH_EVENT
  AUTH_EVENT -->|"still eligible"| BUILD
  AUTH_EVENT -->|"ineligible or logged out"| REMOVE --> RECONCILE
  BUILD --> PUBLISH --> RECONCILE
  START -. "old snapshots" .-> OLD --> KIND
  KIND -->|"no"| NORMAL --> DROP
  KIND -->|"yes"| AUTH --> INFLIGHT --> DROP
  AUTH --> DROP

Behavior audit

Security invariants

• Bind only to literal 127.0.0.1:0.
• Generate an independent random 256-bit bearer for every connector and resource route in every generation.
• Keep bearers runtime-only, redacted, and mutually exclusive with configured authorization.
• Compare authorization in constant time and reject every request containing Origin, even with a valid bearer.
• A bearer authorizes only its exact route and generation. Ordinary refresh keeps a pinned old route/credential alive while old snapshot/runtime owners remain; an auth-revision change rejects new requests through old routes.
• Recheck the auth-generation access guard immediately before forwarding upstream.
• Bypass ambient proxies only for literal IP loopback URLs; permit redirects only while every hop remains literal loopback, under the normal redirect cap. This policy lives in the shared exec-server HTTP path, not only the Apps adapter.
• Bound complete inventory time, page count, tool count, serialized inventory/cache size, and each Hosted Apps upstream POST response. Enforce response bounds while streaming, before JSON/SSE decoding.
• Pin environment instance, cwd, sandbox state, and permission profile for file reads.
• Restrict connector resource reads to URIs declared by that connector's tools.
• Strip private approval/account context before persistence and before model/rollout serialization.

Reviewer map

Validation

The published prototype head 1043025e passed its GitHub checks on June 26, 2026. The branch is now behind main, and the local rebase is unfinished with conflicts, so this description does not claim that the rebased tree is green. The test strategy follows the risks rather than the file layout:

• Boundary: the verifier checks protected-layer product dependencies/identifiers and explicitly rejects the named in-process transport path in codex-apps and its extension.
• Transport and trust: route/generation bearer isolation, constant-time auth, Origin rejection, literal-loopback redirect/proxy rules, response/inventory/upload bounds, private metadata stripping, and cancellation.
• Publication and lifecycle: warm cache, cold single flight, retry/backoff, last-good fallback, concurrent refresh, immutable/pinned generations, auth rekeying, publication races, stale-generation rejection, and shutdown.
• Generic reconciliation: per-server restart on environment, auth, transport, or elicitation-runtime change and preservation of compatible live clients. Exact manager reuse is covered only without an active Apps extension; Apps-active semantic equality remains a known test/fix gap.
• Core integration: discovery, connector tool calls, auth refresh, approval identity/context, Guardian review, files, resources, plugin attribution/install completion, analytics, presentation, and environment availability.
• Host integration: app-server v2 Apps list/status/resource and runtime-OAuth rejection behavior, Apps auth elicitation, and a real mcp-server Hosted Apps end-to-end test.
• Platforms: Linux, macOS, and Windows CI must be green on the rebased head before landing.

Revised proposed landing stack

Each stage should be independently green. A staged adapter may exist behind tests, but no stage should leave two production implementations active.

1. Generic HTTP safety and bounds — loopback redirect/proxy handling and streaming response limits.
2. Pure ownership extraction — move deterministic naming, raw cache, approval templates, and file-schema transforms to their intended product owner while legacy callers still use them.
3. Runtime MCP registrations — EffectiveMcpServer, the smallest justified runtime bearer/owner/metadata surface, deterministic catalog semantics, and non-Apps proofs.
4. Extension contribution and reconciliation — Current/Discover, revisions, publication-race handling, safe-boundary projection, stable semantic identity, and non-Apps unchanged-client tests.
5. Plugin ownership cleanup — move App declarations to the plugin crate and express selected-plugin attribution through generic contributions.
6. Apps HTTP adapter behind integration tests — immutable generations, connector/resource routes, auth, files, elicitations, and upstream session isolation without production cutover.
7. Apps extension and direct host APIs — lifecycle/policy/presentation/analytics/install ownership plus app-server direct inventory, still without switching the core execution path.
8. Small atomic production cutover — register the ordinary HTTP servers, switch app-server/core consumers, and delete the legacy core/manager Apps path in the same commit.
9. Opaque host boundary and enforcement — reduce mcp-server to generic host composition, enable the boundary verifier, and retain the real-host end-to-end proof.

The app-server status shape, standalone connector suggestions, cold-first-turn semantics, and other intentional behavior changes should land separately or be explicitly approved; they should not inflate the structural cutover.